API для интернет-магазина

Для фискализации онлайн оплат на стороне интернет-магазина необходимо реализовать API для возврата чеков на фискализацию. API должно отдавать по GET запросу список чеков.

Пример списка чеков

Пример ответа

[
  {
    "id": 85,
    "created_at": "2018-01-10T03:57:38+0000",
    "version": 8,
    "type": "sell",
    "email": "my-favorite-client@gmail.com",
    "print": false,
    "items": [
      {
        "name": "Чипсы",
        "price": 100,
        "quantity": 1
      },
      {
        "name": "Сухарики",
        "price": 50,
        "quantity": 12
      }
    ],
    "_links": {
      "lock": {
        "rel": "self",
        "href": "http:\/\/ecommerce.ru\/\/payment-receipts\/85\/actions\/lock"
      },
      "status": {
        "rel": "self",
        "href": "http:\/\/ecommerce.ru\/\/payment-receipts\/85\/status"
      }
    }
  },
  {
    "id": 86,
    "created_at": "2018-01-10T03:57:40+0000",
    "version": 1,
    "type": "return",
    "email": "my-favorite-client@gmail.com",
    "print": false,
    "items": [
      {
        "name": "Чипсы Lays",
        "price": 100,
        "quantity": 1
      },
      {
        "name": "Сухарики",
        "price": 50,
        "quantity": 12
      }
    ],
    "_links": {
      "lock": {
        "rel": "self",
        "href": "http:\/\/ecommerce.ru\/\/payment-receipts\/86\/actions\/lock"
      }
    }
  }
]

Описание полей

Наименование	Тип данных	Описание
id	Integer|String	Внутренний идентификатор чека в системе интернет-магазина.
created_at	String	Дата создания чека.
version	Integer	Версия чека. Используется для механизма защиты от одновременной печати чеков несколькими аппаратами.
type	String	Тип чека. Может принимать одно из значений: sell – чек продажи return – чек возврата продажи.
email	String	Email клиента, на который будет отправлен кассовый чек.
print	Bool	Печатать или нет бумажный чек. Имеет смысл только если указан email клиента. Если email не указан, то бумажный чек будет напечатан вне зависимости от этой настройки.
items	Array	Массив позиций чека.
_links	Object	Ассоциативный массив с указанием URL для работы.

Описание процесса

Последовательность действий следующая:

1. Outofbox.54-FZ запрашивает список чеков.
2. Приложение в объекте _links ищет ссылку на lock, чтобы исключить вероятность печати чека повторно.
3. Приложение отправляет POST запрос на lock url с указанием version, полученном из предыдущего шага. Здесь реализован механизм OPTIMISTIC LOCK.
4. Интернет-магазин при запросе на lock url должен пометить чек как отпечатанный, либо вообще удалить его из базы, чтобы при последующем запросе списка чеков данный чек больше не появлялся в списке.
5. В случае, если запрос на lock url завершился кодом HTTP 200, то приложение начинает фискализацию данного чека.

Данный процесс запускается с определенной периодичностью.

Отчет о статусе печати чека

Также система может опционально сообщить на удаленный сервер о статусе печати чека. Для этого помимо ссылки lock, следует передать ссылку status. Чеки, у которых задан этот параметр, после печати (успешной или не успешной), будут отправлять информацию о печати на сервер. Делается это посредством POST запроса на указанный URL с передачей в теле сообщения JSON структуры с информацией.

При удачной печати чека

{
  "status": "success",
  "requisites": {
    "date": "13-03-2018",
    "time": "17:59",
    "fdn": "1234",
    "fp": "123456789",
    "session": "123"
  }
}

В объекте requisites будет содержаться информация о чеке:

Наименование	Описание
date	Дата фискализации в формате ДД-ММ-ГГГГ по времени, настроенном на ККМ
time	Время фискализации в формате ЧЧ:ММ по времени, настроенном на ККМ
fdn	Номер документа
fp	Фискальный признак чека
session	Номер смены

При неудачной печати чека:

{
  "status": "error",
  "error": {
    "message": "Ошибка: закончилась бумага"
  }
}

В случае, если по той или иной причине не удалось отправить статус печати чека, например, ошибка на сервере или отсутствует связь, то будут предприняты дополнительные попытки. Всего будет предпринято 10 попыток. Чем больше число попыток - тем дольше между ними будет пауза.

На данный момент попытки будут запускаться со следующей периодичностью:

Номер попытки	Пауза
1	7 секунд
2	20 секунд
3	50 секунд
4	2 минуты
5	7 минут
6	18 минут
7	50 минут
8	2 часа
9	6 часов

Если по прошествию последней попытки отправить информацию не удалось, то попытки прекращаются. При этом в системе сохраняется чек, который не удалось отправить, который можно просмотреть в веб-интерфейсе в разделе «Чеки».